[{"slug":"남이-만든-OpenAPI-스키마-테스트하기","metadata":{"title":"남이 만든 OpenAPI 스키마 테스트하기","publicationDate":"2024-07-09T12:41:00.000Z","preview":"/posts/남이-만든-OpenAPI-스키마-테스트하기/preview.png","summary":"API 클라이언트 코드 자동 생성을 위해 남이 만든 API 서버에 OpenAPI 스키마 붙여보기\n","tags":["TypeScript","Vitest","OpenAPI","OpenAPI Generator"]},"content":" $\"Preview\"$ \n

평소 북마크와 하이라이트를 관리하기 위해 Raindrop을 이용하고 있습니다. 하지만 Chrome 북마크 동기화를 지원하지 않아 항상 아쉽다고 생각하고 있었습니다. Chrome 북마크를 이용하면 북마크 바에서 자주 사용하는 북마크를 바로 이용할 수 있고 검색 또한 훨씬 빠르기 때문입니다.

목마른 자가 우물을 파는 법이라고, 결국 Chrome 확장 프로그램을 직접 만들게 되었습니다. 하지만 Raindrop API를 이용하던 중 공식 API 문서에 많은 문제점을 발견하게 되었는데, API 명세 자체가 설명이 미흡하거나 실제 API 호출 결과와 다르기까지 했습니다. 차라리 직접 OpenAPI 스키마를 정의하는 편이 낫겠다는 생각이 들 정도였습니다.

조금 생각해보니 직접 스키마를 정의해서 쓰는 것이 의외로 나쁘지 않은 생각인 듯 했습니다. 스키마를 한 번 만들어두면 언어를 막론하고 코드 생성기를 이용해 코드를 자동 생성할 수 있을 것이고, 다른 프로젝트에서도 쉽게 재사용할 수 있으니까요. 그렇게 만든 것이 lasuillard/raindrop-client입니다.

❓ OpenAPI란?

OpenAPI는 HTTP API를 표현에 대한 사양(Specification)입니다. 보통 REST API를 이용해 본 적이 있다면 Swagger를 이용해 본 경험이 있으실겁니다.

$\"Swagger\"$

Swagger는 OpenAPI 문서를 기반으로 자동 생성된 웹 기반 API 클라이언트의 대표적인 예시입니다. OpenAPI를 사용하면 여러 장점이 있습니다.

\n
이해관계자간에 서로 소통하기 위한 정형화된 방법을 제공
\n
API를 정의하고 협의하는 표준화된 방법을 제공하여 API를 유지보수 및 관리하기 위한 효율적이고 체계적인 방법을 제시합니다.
\n
\n
자동화를 통해 작업 효율 증대
\n
Swagger, Redoc, OpenAPI Generator와 같은 도구를 통해 API 문서, 클라이언트 및 서버 코드(의 골조) 등을 자동 생성하여 반복적이고 정형화된 작업을 자동화할 수 있습니다.
\n
\n
개발자 경험(DX) 개선
\n
개발자는 반복적이고 정형화된 작업에 쉽게 질리기 마련입니다. 제가 보아온 개발자는 보통 기능 개발을 선호하지 문서 관리를 하고 싶어하는 경우는 거의 없었습니다.
\n

OpenAPI를 활용하는 대표적인 Python 프레임워크는 FastAPI를 예로 들 수 있습니다. API 엔드포인트 구현(주석, 타입 어노테이션 등)으로부터 OpenAPI 스키마를 자동 생성하며 데이터 모델을 관리하는 것으로 API 문서 관리 대부분을 자동화할 수 있으며 구현과 문서 사이의 괴리를 최소화합니다.

🪛 OpenAPI Generator

OpenAPI Generator는 OpenAPI 스키마로부터 API 클라이언트 및 서버 코드를 생성하는 도구입니다. Mustache 템플릿 언어를 통해 다양한 언어와 프레임워크를 지원하며 사용자 정의 템플릿을 이용할 수도 있습니다. OpenAPI Generator로 생성된 코드 예시는 다음과 같습니다.

/**\n * AuthenticationApi - functional programming interface\n * @export\n */\nexport const AuthenticationApiFp = function(configuration?: Configuration) {\n    const localVarAxiosParamCreator = AuthenticationApiAxiosParamCreator(configuration)\n    return {\n        /**\n         *\n         * @param {string} redirectUri\n         * @param {string} clientId\n         * @param {*} [options] Override http request option.\n         * @throws {RequiredError}\n         */\n        async authorize(redirectUri: string, clientId: string, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<void>> {\n            const localVarAxiosArgs = await localVarAxiosParamCreator.authorize(redirectUri, clientId, options);\n            const localVarOperationServerIndex = configuration?.serverIndex ?? 0;\n            const localVarOperationServerBasePath = operationServerMap['AuthenticationApi.authorize']?.[localVarOperationServerIndex]?.url;\n            return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath);\n        },\n

이렇게 생성된 코드는 다음과 같이 이용할 수 있습니다.

// Create Axios instance\nconst instance = axios.create();\nconst rateLimited = rateLimit(instance, { maxRPS: 5 });\n\n// Create API client\nconst accessToken = process.env.RAINDROP_API_TOKEN;\nconst client = new Raindrop(new Configuration({ accessToken }), rateLimited);\n\n// Make some call\nconst response = await client.collection.searchCovers('strawberry');\nconsole.log(response.data);\n

현재 raindrop-client는 typescript-axios 템플릿을 이용하여 클라이언트 코드를 자동 생성하고 npm 패키지 레지스트리로 배포하게끔 CI가 구성되어 있습니다.

🧪 스키마 테스트하기

OpenAPI 스키마를 가져다 쓰는 경우라면 스키마를 굳이 까다롭게 테스트할 필요가 없습니다. 보통 서버를 구현하는 측에서 테스트하기 때문입니다. 하지만 이번엔 조금 상황이 특별합니다. Raindrop에서 제공하는 OpenAPI 스키마가 없고 스키마를 직접 제3자인 제가 작성하기 때문입니다. 그래서 실제로 작성한 스키마의 요청과 응답이 예상대로인지 확인할 필요가 있습니다.

\n
동작(데이터) 테스트
\n
요청에 대해 응답이 정상적으로 돌아오는지, 기본적인 API 호출에 대한 테스트가 필요합니다.
\n
\n
스키마(타입) 테스트
\n
스키마를 테스트하기 위해 타입 체커(TypeScript)를 이용하고자 했지만 런타임 수준에서 응답 스냅샷(JSON 문자열)에 대한 동적인 타입 체크를 구성할 수 있는 방법을 찾을 수 없었습니다.
\n

그래서 우선 스키마를 테스트할 수 있는 다른 도구들을 찾아보았고, Schemathesis를 알게 되었습니다.

😎 Schemathesis

Schemathesis는 API 스키마를 테스트하기 위한 도구입니다. API 안정성, 성능, 보안 등 여러 부분을 테스트할 수 있으며 CI 통합, 리포트 등 다양한 추가 기능을 제공합니다. OpenAPI 뿐만 아니라 GraphQL 스키마도 지원하는 것으로 보입니다.

$\"Schemathesis\"$

Schemathesis는 꽤나 매력적이었지만 최종적으로 이용할 수는 없었습니다.

\n
API Fuzzing을 이용하여 테스트 중 많은 API 호출을 보내게 됩니다. 직접 구축하고 관리하는 서버라면 괜찮겠지만 실 서비스에 대해 많은 API 호출을 보내는 것은 IP 또는 계정 차단, 레이트 제한 가능성이 있습니다.
\n
\n
실 서비스 대신 모의 서버(e.g. Mockoon)를 구성해서 테스트 데이터셋을 관리하고자 하였으나 너무 구성이 복잡해졌고 UI를 통한 데이터의 변경 및 갱신이 불편했습니다.
\n
\n
Schemathesis를 커스터마이징하기 위해서는 Python을 이용해야 하는데 현재 프로젝트는 TypeScript를 이용하므로 언어를 추가하는 것은 구성을 필요 이상으로 복잡하게 만든다고 판단했습니다.
\n

분명 흥미로운 도구였지만 이번엔 용도와 목적에 맞지 않아 다음을 기약하기로 했습니다. 언젠가 직접 API 서버를 구축한다면 써봄직할 것 같습니다.

🐦 Polly.js

결국 API 호출, 호출 내역을 캐싱하고 스냅샷을 이용해 기본 API 동작을 테스트하기로 했습니다. Python에서는 pytest-recording을 이용하지만 Node에서도 비슷한 기능을 제공하는 Polly.js를 찾을 수 있었습니다.

Polly.js는 Netflix에서 공개한 오픈 소스로, HTTP 트래픽을 녹화, 재생 및 스텁(Stub)하는 기능을 제공합니다. JavaScript로 작성되어 있으며 특정 프레임워크에 의존하지 않는 독립적인 라이브러리입니다.

그리고 Vitest의 Fixture 기능을 이용해서 pytest와 거의 동일한 방식으로 여러 테스트 의존성 주입을 비교적 편하게 관리할 수 있습니다.

import NodeHTTPAdapter from '@pollyjs/adapter-node-http';\nimport { Polly } from '@pollyjs/core';\nimport FSPersister from '@pollyjs/persister-fs';\nimport type { Use } from '@vitest/runner';\nimport type { Task } from 'vitest';\nimport { taskId } from './common';\n\nPolly.register(NodeHTTPAdapter);\nPolly.register(FSPersister);\n\nexport async function polly({ task }: { task: Task }, use: Use<Polly>) {\n\tconst _polly = new Polly(taskId(task), {\n\t\tadapters: ['node-http'],\n\t\tpersister: 'fs',\n\t\tpersisterOptions: {\n\t\t\tfs: {\n\t\t\t\trecordingsDir: 'tests/__recordings__'\n\t\t\t}\n\t\t},\n\t\trecordFailedRequests: true,\n\t\tmatchRequestsBy: {\n\t\t\theaders: {\n\t\t\t\texclude: ['authorization']\n\t\t\t}\n\t\t}\n\t});\n\t_polly.server.any().on('beforePersist', (_, recording) => {\n\t\trecording.request.headers = recording.request.headers.map(\n\t\t\t// @ts-expect-error Don't care\n\t\t\t(header: Header) => {\n\t\t\t\tif (header.name === 'authorization') {\n\t\t\t\t\theader.value = '<REDACTED>';\n\t\t\t\t}\n\t\t\t\treturn header;\n\t\t\t}\n\t\t);\n\t});\n\tawait use(_polly);\n\tawait _polly.stop();\n}\n

Polly.js가 요청을 분석해서 그 요청이 기존에 이미 녹화되어 있으면 저장된 응답을 반환하고, 그렇지 않으면 실제 요청을 보냅니다(설정을 통해 이 동작 또한 변경할 수 있음). 테스트 코드를 갱신하고 싶으면 모든 녹화 데이터를 삭제하면 됩니다.

👻 스냅샷과 타입 체크

가능한 테스트 데이터 관리를 편하게 하기 위해 스냅샷으로부터 스키마 테스트가 가능하게 하고자 했습니다. 또한 임의의 JSON 문자열에 대해 타입 체크를 할 수 있는 방법을 찾지 못했기에 대안을 모색해야 했습니다.

\n
스냅샷 생성 시 문자열이 아니라 객체를 그대로 삽입할 수 있도록 커스텀 스냅샷 구현을 작성
\n
스냅샷 구현의 소스 코드를 뜯어보니 스냅샷을 삽입할 때 테스트 파일을 수정하게끔 구현되어 있었습니다. 조금 손보면 문자열이 아닌 객체를 그대로 저장하는 것 또한 가능해 보였습니다.
\n
\n
스냅샷 생성 중 타입 체크를 위한 테스트 파일을 동적으로 생성
\n
테스트 라이브러리를 커스터마이징하기엔 너무 버거워질 것 같아 테스트를 생성하는 것이 훨씬 간단할 듯 했습니다.
\n

구현과 관리를 단순히 하기 위에 후자를 택했습니다. 그리고 지금 사용중인 Vitest 테스트 프레임워크에서 스냅샷이 갱신될 때 동작을 주입하기 위해 Snapshot Serializer를 이용해야 했습니다.

export async function generateTypeTest(\n\t{ task, expect }: { task: Task; expect: ExpectStatic },\n\tuse: Use<RegisterHook>\n) {\n\tconst hookFn: RegisterHook = (args: RegisterHookArgs) => {\n\t\t// Check test file generation registered only once\n\t\tlet ack = false;\n\n\t\t// Add snapshot serializer as an workaround for hook to generate type tests\n\t\texpect.addSnapshotSerializer({\n\t\t\tserialize(val, config, indentation, depth, refs, printer) {\n\t\t\t\taddTest({\n\t\t\t\t\ttestId: taskId(task),\n\t\t\t\t\ttype: args.type,\n\t\t\t\t\tvalue: JSON.stringify(val)\n\t\t\t\t});\n\t\t\t\tack = true;\n\t\t\t\treturn printer(val, config, indentation, depth, refs);\n\t\t\t},\n\t\t\ttest() {\n\t\t\t\treturn !ack;\n\t\t\t}\n\t\t});\n\t};\n\tawait use(hookFn);\n}\n

여기에 테스트를 생성하는 코드를 삽입하여 타입 테스트를 동적으로 생성합니다.

function generateTest(dir: string, item: CreateTest): string {\n\tconst filepath = path.join(dir, `${item.testId}.test-d.ts`);\n\tconst content = `\\\nimport { assertType, it } from 'vitest';\nimport type { ${item.type} } from '~/generated/api'\n\nit('${item.testId}', () => {\n  assertType<${item.type}>(\n    ${item.value}\n  )\n})\n`;\n\tconsole.debug(`Will generate file ${filepath} with content: \\n\\n ${content}`);\n\tfs.writeFileSync(filepath, content);\n\n\treturn filepath;\n}`\n

테스트가 실행되고 나면 아래와 같은 테스트 파일이 생성되며 커밋하여 소스 코드의 일부로 관리됩니다.

it('parseURL', async ({ client, expect, generateTypeTest }) => {\n\tconst response = await client.import.parseURL('https://example.com');\n\n\tgenerateTypeTest({ type: 'ParseURLResponse' });\n\texpect(response.data).toMatchInlineSnapshot(`\n\t\t{\n\t\t  \"item\": {\n\t\t    \"cover\": \"<screenshot>\",\n\t\t    \"excerpt\": \"\",\n\t\t    \"media\": [],\n\t\t    \"meta\": {\n\t\t      \"tags\": [],\n\t\t    },\n\t\t    \"title\": \"Example Domain\",\n\t\t    \"type\": \"link\",\n\t\t  },\n\t\t  \"result\": true,\n\t\t}\n\t`);\n});\n

먼저 단위 테스트 코드가 실행되어야 타입 테스트 코드가 생성되므로 두 테스트를 별도 과정으로 나누어 실행하게 됩니다.

📡 정리하며

OpenAPI 스키마의 관리 주체가 이번 경우처럼 서비스 제공자가 아닌 제3자인 이번 경우에는 고려해야 할 사항이 많았습니다. 스키마를 만들면 끝인 것이 아니라 지속적으로 변경 사항을 추적하기 위한 자동화도 고안해야 할 필요가 있구요.

raindrop-client는 Raindrop Sync for Chrome 프로젝트를 위해 만들어졌습니다. 이직 전 잠시 쉬던 중 시작했고 이직 후 짬을 내지 못해 프로젝트가 시작한 지 너무 오랜 기간 진전되지 못했지만 이제 기본적으로 동작하는 프로토타입을 만들기 위해 좀 더 많은 노력을 기울이고 있습니다. 일과 다른 공부로 바쁘지만 틈틈이 짬을 내려고 합니다.

관련된 프로젝트는 모두 공개된 오픈 소스이니 관심이 있다면 둘러보시길 바랍니다.

"},{"slug":"개발을-위한-데이터베이스","metadata":{"title":"개발을 위한 데이터베이스","publicationDate":"2024-06-12T10:45:23.000Z","preview":"/posts/개발을-위한-데이터베이스/preview.jpg","summary":"개발 환경을 위해 데이터 추출하기\n","tags":["AWS","RDS","S3","Route 53","GitHub Actions","PostgreSQL"]},"content":" $\"Preview\"$ \n

현재 일터에서는 Postgres 데이터베이스를 이용하고 있습니다. 기능 개발, 버그 수정 등 개발 전반에서 다양한 데이터를 필요로 하기에 데이터를 추출하기 위해 pg_dump와 pg_restore를 이용하고 있었지만 데이터가 점차 쌓이면서 추출과 적재에 소요되는 시간이 계속 늘어가고 있었고, 개인정보 보호 및 보안 강화에 대한 요구 사항도 늘어만 갔습니다.

점점 체계적인 데이터 추출 방법을 고안할 필요가 점점 늘어만 가고 있었기에 이번에 개발팀이 데이터를 안전하게 추출하고 쉽게 이용할 수 있도록 하는 방법을 찾아보게 되었습니다.

🔎 데이터 추출 방법

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

방법	사용성	속도	선택적 데이터 추출	비용	유지보수성
`pg_dump`, `pg_restore`	좋음	DB 크기 비례	O (테이블 단위)	낮음	좋음 (관리 쉬움)
무작위 데이터 생성기	나쁨	빠름 (DB 연결 불필요)	X	낮음	낮음 (모든 데이터 정합성, 요건 관리)
데이터 샘플링	보통	느림 (네트워크 의존)	O	낮음	보통 (스키마 변경에 따른 SQL 관리 필요)
데이터베이스 로테이션	좋음	보통	X	높음 (운영 DB 복제본 운용)	좋음 (스키마 변경에 큰 영향 받지 않음)

💻 `pg_dump`, `pg_restore`

이미 사용하고 있었던 pg_dump와 pg_restore는 유용하지만 이미 상당한 시간이 소요되고 있었고 민감한 개인정보 사본이 가능한 많은 곳에 떠돌아다니는 것은 최소화하고자 가장 먼저 제외했습니다.

또한 격리된 네트워크 내 데이터베이스에 접근하기 위해 SSH 터널링을 이용해야 했고 키 및 설정 관리 등이 복잡했으며 SSH 대신 AWS SSM Session Manager를 이용하도록 네트워크 구성을 전체적으로 개편하면서 데이터 전송 속도가 크게 느려졌기에 더 이상 쓸 수 없는 지경에 이르렀습니다.

🔤 무작위 데이터 생성기

factory_boy, Faker를 이용하면 원하는 데이터를 쉽고 빠르게 생성할 수 있습니다. 하지만 서비스 특성상 수치적인 정합성이 중요하고 현실과의 괴리(결함을 포함하여)를 최소화하는 무작위 데이터셋을 생성하고 관리하는 것은 쉽지 않습니다.

테스트를 위해서는 계속 이용하지만 범용적으로 이용할 수 있는 데이터셋을 구성하기에는 부적합하다고 판단하여 제외했습니다.

🧪 데이터 샘플링

SQL 스크립트를 작성하여 필요한 데이터를 추출하는 가장 직관적인 방법입니다. 쉘 스크립트를 이용할 수도 있지만 안정적인 구현과 유지보수 및 관리 편의를 위해 개발팀 주 언어인 Python을 이용하기로 했습니다.

🔁 데이터베이스 로테이션

개발 데이터베이스를 운영 환경의 데이터베이스 스냅샷으로부터 재생성하는 방법입니다. AWS DMS (Database Migration Service)와 같은 대안도 있었지만 현재 데이터베이스 크기를 감안했을 때 이 방법이 더 쉽고 저렴할 것이라는 조언을 받아 DMS는 추후 데이터베이스가 훨씬 더 커졌을 때 시도하기로 하였습니다.

🪣 S3를 이용한 데이터 샘플링

처음 시도했던 방식은 AWS RDS for Postgres를 위한 공식 aws_s3 확장 프로그램¹ ²을 이용하는 것입니다. IAM 역할, S3 버켓 ACL, RDS 설정 정도만 구성해주면 바로 이용할 수 있습니다.

\n $\"RDS$ \n

장점은 AWS에서 제공하는 확장 프로그램 aws_s3을 이용하므로 복잡한 설정이나 구성이 필요하지 않다는 것입니다. 또한 저렴한 S3에 데이터셋을 저장해두고 공유하거나 재사용할 수 있습니다.

하지만 단점으로는,

S3 버켓, 추출된 데이터를 저장하고 불러오기 위한 경로와 파일 이름의 규칙 등 균일화된 추출 및 적재 방식을 정의하고 관리하기 위한 함수와 프로시저를 관리해야 하고,
PL/pgSQL 자체가 친숙하지 않으면 사용 및 관리가 어려우며,
aws_s3 확장 프로그램은 오픈 소스가 아니어서 오픈 소스 레플리카인 chimpler/postgres-aws-s3를 이용해야 했습니다. 이는 로컬 환경의 데이터베이스 구성을 복잡하게 만들었습니다.

구성 후에는 사용성과 실용성이 떨어져 거의 사용하지 않았고 결국 다른 방법을 찾아야 했습니다.

Postgres 확장 프로그램을 이용해보는 것은 처음이었는지라 흥미로웠고 버리기엔 아까워서 잠시 개인 시간에 짬을 내어 구성을 재현(³)해 남겨두었습니다. S3 대신 MinIO를 이용하지만 사용 방식에 큰 차이는 없습니다.

🐳 GitHub Actions + ECR을 이용한 데이터 샘플링

앞선 방식의 가장 큰 문제는 구성이 복잡하다고 사용성이 너무 떨어진다는 점입니다. 그래서 생각한 방법은 데이터가 적재된 데이터베이스 이미지를 생성하고 이를 공유하여 이용할 수 있게 한다면 비교적 쉽게 이용할 수 있을 것이라고 판단했습니다. 데이터베이스 컨테이너를 생성해서 연결하기만 하면 되니까요.

그리고 이 작업을 GitHub Actions를 이용해 워크플로로 정의해두고 언제든지 실행할 수 있게끔 하면 될 것입니다. 하지만 실제 구성에는 여러 문제가 있었습니다.

\n
네트워크 문제
\n
aws_s3 확장을 쓸 때에는 데이터가 S3를 경유하였기에 네트워크를 크게 신경쓸 필요가 없었습니다. 하지만 데이터베이스와 직접 연결을 맺고 쿼리를 수행하는 방법으로 변경하면서 RDS에 접속하기 위한 방법을 찾아야 했습니다.
\n
개발팀은 내부 리소스에 접근하기 위해 SSM Session Manager를 이용하고 있었고, 이 방법을 그대로 사용하기로 했습니다. 하지만 Session Manager의 낮은 네트워크 대역폭으로 데이터를 추출하는 데 상당한 시간이 소요되었습니다.
\n
하지만 Python 스크립트를 이용해 필요한 선택적 데이터만을 추출할 것이니 그 용량이 방대하지는 않을 것이고, 디버깅 및 테스트를 위한 데이터셋 등 한정적인 용도로 이용할 것이어서 속도를 크게 신경쓰지는 않기로 했습니다. 필요하다면 aws_s3 확장을 활용하여 속도를 크게 개선할 수 있을 테니까요.
\n
\n
보안 문제
\n
데이터베이스 인증 정보를 비롯, 그 어떤 인증 정보도 반복적으로 노출될 기회는 줄여야 합니다. 샘플링 작업을 위해 마스터 계정을 이용하는 대신 최소 권한의 읽기 전용 계정을 할당하고 IAM 기반 RDS 인증⁴을 이용해 임시 인증 정보를 발급하여 이용하기로 했습니다.
\n
\n
데이터 추출 및 적재
\n
데이터베이스 스키마는 pg_dump를 이용할 수 있었고, 목적 데이터 또한 추출에는 큰 문제가 없었지만 추출된 데이터를 다시 적재하는 데에 골머리를 많이 썩였습니다.
\n
- \n
  외래 키 제약 조건
  \n
  달리 언급하지는 않았지만 aws_s3 확장을 이용할 때에도 동일하게 발생했던 문제입니다. 데이터 적재 시 다양한 제약 조건(대표적으로 외래 키)으로 인해 문제가 발생했습니다. 이전 방법에서는 의존성에 맞추어 데이터 적재 순서를 조절했지만 이는 여간 귀찮은 일이 아니었습니다. 추가적인 조사 후 session_replication_role 설정 파라미터를 이용해서 제약 조건을 무시하고 데이터를 적재할 수 있다는 것을 알게 되었습니다.
  \n
- \n
  시퀀스 문제
  \n
  COPY를 이용해 데이터를 적재할 경우 관련된 시퀀스가 갱신되지 않는 문제가 있었습니다. 갱신되지 않은 시퀀스로 인해 로컬 서버 동작 중 새로운 객체가 생성될 때 문제를 일으켰습니다.
  \n
  pg_dump를 이용해 데이터를 추출하면 실행 가능한 INSERT SQL문을 뽑아낼 수 있어서 문제가 발생하지 않았지만 이번 데이터 추출 방식에서는 COPY 명령어를 이용하고 있었습니다. 이 문제는 데이터를 적재한 뒤 시퀀스를 일괄 갱신⁵하는 것으로 해결하였습니다.
  \n
\n
\n
적재 후 데이터베이스 이미지 생성
\n
데이터베이스 컨테이너를 실행한 뒤 스키마 초기화 및 데이터 적재, 시퀀스 갱신 후 데이터베이스 이미지를 커밋하는 것으로 충분하리라 생각했지만, 예상치 못한 문제가 있었습니다.
\n
- \n
  볼륨에 저장된 데이터는 커밋 시 이미지에 포함되지 않음
  \n
  Postgres 컨테이너의 데이터 볼륨(/var/lib/postgresql/data)은 이미지에 포함되지 않아 컨테이너 실행 후 데이터가 비어있는 문제가 있었습니다. 데이터 위치(PGDATA)를 다른 곳으로 지정(/data)하여 해결하였습니다. 개발 및 테스트 목적으로만 이용할 것이기 때문에 컨테이너의 데이터 볼륨에는 크게 신경쓸 필요가 없기 때문입니다.
  \n
- \n
  docker image commit 시 이미지로부터 컨테이너를 실행하면 Redo 작업이 실행됨
  \n
  이미지로부터 컨테이너를 시작하면 Redo 작업이 실행되는 문제가 있었습니다. 데이터 자체에 큰 문제는 없었지만 이 작업으로 인해 컨테이너 시작이 느려졌다. 문제 원인을 조금 더 확인해 본 결과 데이터베이스 이미지를 커밋하기 전 정상적으로 중단시키지 않았기 때문이었으며 이미지를 커밋하기 전 컨테이너를 정상적으로 중지(docker container stop)시키는 것으로 해결되었습니다.
  \n
\n

구성된 워크플로는 다음과 같았습니다.

graph TB\n    start-db-container[Start DB container] -->\n    generate-db-auth-token[Generate RDS auth token] -->\n    ssm-forwarding-session[Start SSM forwarding session to RDS] -->\n    create-connection[Connect to RDS] --> Sampling\n\n    subgraph Sampling\n        direction TB\n        subgraph RDS\n            dump-schema[Dump schema using `pg_dump`] -->\n            extract-data[Extract data]\n        end\n        RDS --> Container\n        subgraph Container\n            load-schema[Load schema] -->\n            load-data[Load data] -->\n            update-sequences[Update sequences]\n        end\n    end\n\n    Sampling -->\n    stop-db-container[Stop DB container] -->\n    commit-db-image[Commit DB container] -->\n    push-to-ecr[Push image to ECR]\n

이로써 일부 사용자와 연관된 모든 데이터를 선택적으로 추출한다는 일차적인 목표는 달성할 수 있었습니다. 하지만 이와 연관된 인프라 구성, 워크플로 스크립트 관리 부담이 늘었고 무엇보다 일반적인 개발 시나리오에서 부분적인 샘플링 데이터만을 필요로 하는 경우가 현재로서는 잘 없었습니다.

그렇게 반쪽짜리 성공을 뒤로 하고 다음 대안을 시도하기로 했습니다.

↪️ 데이터베이스 로테이션

앞선 방식은 범용 개발 환경을 위해 데이터를 준비하는 용도로는 적합하지 않았기에 결국 운영 데이터베이스 사본을 직접 이용하는 것이 가장 바람직하다는 결론에 도달했습니다. 샘플링은 추후 복잡한 테스트 시나리오를 위한 데이터셋을 준비하기 위해 쓰기로 했습니다.

AWS RDS는 정해진 시간에 스냅샷을 생성합니다. 그리고 이 스냅샷으로부터 데이터베이스를 복원할 수 있습니다. 데이터 용량에 따라 복원에 소요되는 시간은 다르지만 간단한 실험을 통해 확인해보니 생각보다 그리 오래 걸리지 않았으며 현재 데이터베이스 크기, 데이터 증가 추세 등 여러 부분을 검토했을 때 생각할 수 있는 최선이라고 결론을 내렸습니다.

추가로 다음과 같은 사항들을 고려했습니다.

\n
비용 문제
\n
운영 환경과 동일한 성능, 구성 및 크기의 데이터베이스를 개발 환경을 위해 유지한다는 것은 다소 부담스러운 선택지일 수 있습니다. 다만 현재 데이터베이스 규모와 데이터 증가 추세를 감안했을 때 한동안 큰 부담이 되지 않을 것이라고 보았다.
\n
\n
설정 재현 및 기존 데이터베이스 교체 방법
\n
새로운 데이터베이스를 생성하고, 이 데이터베이스로 모든 연결을 다시 맺게끔 하여야 합니다. 서버에서 데이터베이스 연결이 가능하도록 네트워크 및 보안 그룹 구성 또한 유지해야 합니다. 현재 네트워크 설정은 자주 바뀌고 있지 않으며 개발 환경이니 장기간의 다운타임도 허용할 수 있고, 즉각적으로 오류 경보를 받을 수 있기 때문에 너무 복잡하게 생각하지 않기로 했습니다.
\n
데이터베이스 교체는 도메인 레코드(Route 53)를 이용하여 비교적 쉽게 해결할 수 있습니다. 먼저 새 복제본을 만든 뒤 작업이 모두 성공적으로 완료되면 도메인 레코드를 갱신, 기존 데이터베이스는 삭제하면 됩니다.
\n
처리가 더 어려운 것은 리소스 상태 추적이었는데, Terraform과 같은 IaC를 이용하지 않았기 때문입니다. 대신 정해진 접두사(e.g. app-dev-)를 가진 RDS들을 로테이션 대상으로 처리하게끔 하였으며 실수나 버그로 하여금 다른 RDS에 위험한 동작을 수행하지 않도록 IAM에서 해당 접두사를 가진 RDS에만 위험 동작을 수행할 수 있게끔 극히 제한적인 권한만을 부여했습니다.
\n
\n
민감한 정보의 처리
\n
개발 환경은 비교적 보안이 취약해지기 쉽습니다. 개발 편의를 위해 일부 보안 기능을 끈다던가 하는 일도 비일비재합니다. 민감 정보의 유출을 원천 차단할 수 있게끔 마스킹하거나 스크러빙하는 후처리 또한 구현하기로 했습니다.
\n
- \n
  마스터 계정을 포함한 개인 데이터베이스 계정 또한 복제된다는 문제가 있습니다. 마스터 계정 비밀번호는 RDS 복원 직후 강제로 새 비밀번호를 설정하고, 시스템 및 필요한 일부 서비스 계정(샘플링)을 제외한 모든 계정은 비밀번호를 제거하여 로그인할 수 없게 처리했습니다. 물론 최선의 방법은 비밀번호 대신 임시 인증 토큰(generate-db-auth-token)을 사용하는 것입니다.
  \n
- \n
  개발 중 사용자에게 실수로 문자메시지나 이메일이 발송된다거나 하는 불상사 또한 방지하고 싶었기에 이러한 정보는 난수 처리, 삭제, 회사 이메일 / 전화번호 등으로 대체하도록 했습니다.
  \n
\n
\n
자동화
\n
이러한 작업은 그 빈도가 잦지 않다면 사람이 직접 처리할 수 있습니다. 하지만 이런 (귀찮고 지루한) 작업을 반복하다 보면 실수할 가능성이 높습니다. 더군다나 인프라 구성 요소와 관련된 요소가 많다면 실수할 가능성이 더 높아집니다. 그래서 GitHub Actions 워크플로를 작성하여 BE 개발자 누구나 원하는 때에 실행할 수 있도록 만들었습니다.
\n

graph TB\n\tget-latest-snapshot[Get latest snapshot of RDS]\n\t--> restore-from-latest-snapshot[Restore new RDS from snapshot]\n\t--> update-master-password[Update master user password]\n\t--> start-ssm-forwarding-session[Start SSM forwarding session]\n\t--> connect[Connect to RDS]\n    --> run-postproc[Run postprocessing SQL scripts]\n\t--> update-route53-record[Update Route 53 record]\n\t--> delete-old-rds[Delete old RDS]\n

실제로 구현해보니 그 구성과 구현이 그리 어렵지는 않았습니다. 다른 작업들에 비하면 훨씬 간단하고 결과물도 만족스러웠습니다. 도메인 변경 전후로 일시적인 다운타임이 발생하기는 하지만 개발 환경이라 신경쓸 필요는 없는 수준이었습니다.

아무래도 가장 큰 단점은 비용인데 데이터베이스 인스턴스 타입이 바뀌면서 비용 증가를 쉽게 확인할 수 있었기 때문입니다. 하지만 개발팀의 생산성과 편의성을 개선하는 효과가 더욱 컸다고 생각합니다.

🤔 정리하며

앞서 이야기한 방식들은 모두 장단점이 있고 사용 목적 또한 달라 무엇이 최선이다 말할 수는 없는 것 같습니다. 샘플링은 데이터베이스 규모가 충분히 커서 일부 데이터만을 추출하는 체계적인 과정이 필요할 경우 유용할 것으로 보이는 반면, 로테이션은 데이터베이스가 작아 데이터를 동기화할 때 유용한 듯 합니다.

\n
Exporting data from an RDS for PostgreSQL DB instance to Amazon S3\n ↩
\n
\n
Importing data from Amazon S3 into an RDS for PostgreSQL DB instance\n ↩
\n
\n
lasuillard/postgres-examples ↩
\n
\n
IAM database authentication for MariaDB, MySQL, and PostgreSQL ↩
\n
\n
Fixing Sequences - PostgreSQL wiki ↩
\n

"},{"slug":"기술-블로그-시작하기","metadata":{"title":"기술 블로그 시작하기","publicationDate":"2023-11-03T07:39:00.000Z","preview":"/posts/기술-블로그-시작하기/preview.png","summary":"SvelteKit으로 만드는 마크다운 블로그\n","tags":["SvelteKit","GitHub Actions","GitHub Pages","Tailwind CSS","TypeScript"]},"content":"

$\"Preview\"$

지금껏 개인 블로그를 운영한 적이 없었습니다. 경력을 시작한 지 얼마 되지도 않았고, 남과 나눌 수 있는 정도의 지식이나 경험을 가지고 있지 않았으며 무엇보다 필요성을 느끼지 못했기 때문이었습니다.

하지만 이번에 다니던 직장을 퇴사하고 시간이 좀 생겼고, 이직을 준비하며 차일피일 미루던 기술 블로그를 시작하기로 다짐했습니다.

블로그를 통해 무엇을 얻을 수 있을까? 생각해 본 것으로는,

\n
지식 저장 및 공유를 통한 피드백
\n
공개된 글을 작성하게 되면 책임감 있고 정제된 글을 작성하는 데 도움이 될 것이라고 생각했습니다. 신중한 단어 선택이나 가독성을 염두에 둔 구조화된 문서 작성 능력을 기를 수 있지 않을까 기대했습니다.
\n
\n
학습 효과
\n
글을 작성하며 경험을 복기하고 정리하면서 다시 복습하는 효과를 기대할 수 있을 것입니다.
\n
\n
자기 PR
\n
아직까지 제대로 된 경력 기술이나 포트폴리오가 없었고 지금 진행중인 여러 개인 프로젝트의 진척과 경험을 기록해두면 언젠가 도움이 될 것입니다.
\n

블로그를 시작하기로 다짐했으니 어디서 어떻게 호스팅 할지 조사해보습니다.

🔎 블로그 플랫폼 찾아보기

선택할 수 있는 많은 블로그 플랫폼이 있고 각자의 장단점이 있습니다. 지금껏 블로그에서 글을 보기만 했지 작성한 적은 없으니, 비용, 편의성, 개인화, 수익 창출을 주요 비교 척도로 삼았습니다.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

블로그 플랫폼	비용	편의성	개인화	수익 창출
WordPress	(제한적) 무료	좋음	O	O
Medium	무료	보통	X	X
GitHub Pages	무료	낮음	O	O
Velog	무료	좋음	△	O

Medium의 경우 파트너 프로그램이 작성일 기준 한국을 지원하지 않는¹ 것으로 보입니다.

\n
GitHub Pages의 경우 정적 웹 사이트를 무료로 배포할 수 있습니다.
\n
\n
Tistory와 Blogger는 분명히 더 나은 대체재(Velog, WordPress)가 있다고 생각되어 제외했습니다.
\n
\n
언젠가는 다국어 블로그로 발전시키고 싶기에 이용자가 국내 일부에 크게 제한된 일부 플랫폼(네이버 블로그 등) 또한 제외했습니다.
\n

최종 발탁된 플랫폼은 GitHub Pages에 직접 정적 웹 사이트를 개발 및 배포하는 것입니다. 원하는 기능을 구현하는 데 있어 제약이 거의 없다는 점이 가장 큰 이유였습니다. 대신 모든 기능을 직접 구현해야 한다는 문제가 있지만 최근 토이 프로젝트를 통해 프론트엔드 기술을 접할 기회가 있었고 이로 인해 다소 흥미도 생겼기에 배움의 기회로 삼기로 했습니다.

정적 웹 사이트로 배포될 경우 서버가 필요한 일부 기능(조회수, 댓글 등)을 구현하는 데 있어 다소 제약이 따르겠지만 필수적인 기능도 아니고, 절대 불가능한 것도 아니어서 크게 신경쓰지는 않기로 했습니다.

🛠️ 웹 프레임워크 선택

백엔드 개발자로서 프론트엔드 개발을 주도적으로 맡은 적은 없습니다. 학부생 시절 Express.js 및 Vue 2, Nuxt.js를 이용해 팀 프로젝트를 수행한 적은 있었지만 졸업 이후로는 프론트엔드 개발을 한 적이 없습니다.

하지만 여러 아이디어를 구체화하고 싶어서 토이 프로젝트를 시작하다 보면 언젠가는 사용자 인터페이스가 필요하기 마련입니다. 그리고 마침 Svelte를 접하게 되었고 Svelte의 문법 및 구조가 간결하고 정돈되었으며 직관적이라는 인상을 받으면서 왠지 모르게 이끌려 배우기 시작했습니다. 또한 연관 생태계가 활발하고 폭발적으로 성장하고 있었습니다.

그렇게 선택한 프레임워크는 Svelte 위에 만들어진 SvelteKit입니다. 대략적인 SvelteKit의 특징은 다음과 같습니다.

\n
다양한 렌더링 옵션
\n
SvelteKit의 기본 렌더링 동작은 서버에서 먼저 렌더링한 후 클라이언트에서 하이드레이션(Hydration) 프로세스를 거쳐 브라우저에서 다시 렌더링됩니다.
\n
전통적인 웹 서버(SSR 또는 SSG)를 구현할 수도 있고, SPA(CSR)를 구현할 수도 있습니다. SSR, CSR 모두 이용하는 혼합 렌더링 웹 서비스를 구현하는 것 또한 가능합니다. 일부 페이지는 프리렌더링(Pre-rendering) 되도록 하여 성능 향상을 꾀할 수도 있습니다.
\n

반응성

변수를 선언하고 사용하는 것으로 쉽게 반응성을 구현할 수 있습니다. 반응성을 구현하는 데에는 복잡한 함수 호출이나 까다로운 제약이 존재하지 않습니다.

다음은 반응성을 보여주는 간단한 예시(주: Tailwind를 이용하고 있음)입니다.

<script lang=\"ts\">\n\tlet value = '';\n\t$: reply = 'Received:' + value;\n</script>\n\n<div>\n\t<form>\n\t\t<label for=\"greet\">Greeting</label>\n\t\t<input id=\"greet\" type=\"text\" placeholder=\"Type something...\" bind:value />\n\t</form>\n\n\t<p>{reply}</p>\n</div>\n\n<style lang=\"postcss\">\n\tinput {\n\t\t@apply bg-rose-200;\n\t}\n\tp {\n\t\t@apply mt-2 font-extrabold;\n\t}\n</style>\n

$\"SvelteKit$

\n
상태 관리
\n
내장된 저장소를 이용하여 쉽게 상태를 관리할 수 있습니다. 저장소에 대한 반응성을 구현하는 것 또한 쉽습니다.
\n
\n
파일 경로 기반 라우팅
\n
파일 시스템 구조가 실제 웹 페이지의 구조에 반영됩니다. 학부생 시절 처음 Nuxt.js를 접했을 때에도 개념으로 새로운 것은 아닙니다. 여기에 더해 레이아웃, 동적인 라우팅 파라미터 구성, 파라미터 검증 등 고급 라우팅 기능을 제공하므로 라우팅에 대해 더 많은 제어가 가능합니다.
\n
\n
어댑터
\n
어댑터를 통해 추가 설정 없이(Zero-config) Cloudflare, Netlify, Vercel 등 다양한 플랫폼에 추가 설정 없이(Zero-config) 쉽고 빠르게 배포할 수 있습니다. 원한다면 Node 서버를 구성하거나 정적 웹 사이트로 빌드할 수 있는 어댑터 또한 존재합니다.
\n

🐋 개발 컨테이너 구성

저는 주로 VS Code를 이용합니다. 대부분, 아니 사실상 모든 개발 환경 구성은 개발 컨테이너(Devcontainer)를 이용하고 있습니다. 개발 컨테이너를 이용하면 많은 이점이 있습니다.

\n
개발 환경 구축 및 공유
\n
여러 개발자 또는 기기 간 동일 개발 환경을 쉽게 구축하고 공유할 수 있습니다. Docker Compose를 또한 응용할 수 있으므로 로컬 환경에서 의존 서비스(e.g. 데이터베이스) 구성 또한 간편합니다.
\n
\n
격리된 환경
\n
여러 프로젝트를 다루다 보면 프레임워크 뿐만 아니라 언어 버전도 달라지는 경우가 있습니다. pyenv와 같은 환경 관리자(Environment Manager)를 이용하더라도 pyenv를 통해 Python 인터프리터를 설치하는 과정에 호스트 환경 구성 차이로 인해 문제가 발생하는 경우가 종종 있습니다.
\n
또한 일부 패키지(e.g. psycopg2)의 경우 호스트 환경 의존성을 가지는 경우가 있으며 이러한 패키지 설치 및 관리는 리눅스 배포판에 따라(e.g. apt, apk, yum, ...) 달라질 수 있습니다. 하지만 개발 컨테이너를 이용하면 이러한 간극을 최소화할 수 있습니다.
\n
\n
IDE 프로필 관리 단순화
\n
저는 가능한 호스트 환경에 확장 프로그램을 설치하지 않는 편입니다. Shell, PowerShell, Python 등 모든 프로젝트에 걸쳐 자주 사용되는 일부 확장 프로그램만 설치하여 이용합니다.
\n
프로젝트에서 사용하는 확장 프로그램(Python, LLDB 등)은 개발 컨테이너 내부(.devcontainer/devcontainer.json)에 정의하고 개인적으로 사용하는 공통 확장 프로그램(Git Graph, GitLens 등)은 사용자 설정(dev.containers.defaultExtensions)에 정의하여 자동으로 설치되도록, 프로필을 분리하여 이용하고 있습니다.
\n
\n
GitHub Codespaces
\n
웹 브라우저 또는 VS Code에서 GitHub Codespaces 확장 프로그램을 통해 Codespaces에 연결할 수 있습니다. 무료 계정에 대해 월 120 코어 사용 시간이 제공²됩니다. Codespaces와 같은 원격 개발 환경을 이용하면 Docker를 설치할 필요도 없어지지만 다양한 네트워크 제약, 비용 등의 문제로 필요한 경우에만 이용하는 편입니다.
\n
\n
쓰고 버릴 수 있는(Disposable) 개발 환경
\n
개발 환경을 자주 재구성하게 되면서 개발 환경 자체의 문제점을 파악할 수 있게 됩니다.
\n

물론 단점도 있습니다.

\n
Docker에 대한 상당한 지식 요구
\n
프로젝트 성격에 따라 복잡한 네트워크, 권한 및 볼륨 설정 등을 요하는 경우도 있습니다.
\n
\n
쉽게 메꿀 수 없는 하드웨어 수준의 간극(CPU 아키텍처, GPU 자원 등)
\n
Windows를 사용하는 개발자와 macOS를 사용하는 개발자 간 개발 환경 구성에 간극이 존재하며 이로 인한 문제가 발생할 수 있습니다.
\n
개인적으로 웹 크롤러 개발 중 Selenium 3.x 컨테이너 이미지가 ARM 아키텍처에 대한 지원이 미흡하여 정상적인 환경 구성에 문제를 겪었던 경험이 있었습니다. 하지만 극히 드문 경우는 아니었고 대부분 해결은 가능했습니다.
\n
\n
리소스 공유
\n
기본적으로 격리된 환경에서 일상적으로 이용하는 많은 자원이 공유되지 않을 수 있습니다. GPG, X 디스플레이, SSH 소켓 등 일부 자원에 대한 공유 설정은 VS Code에 의해 기본적으로 처리됩니다.
\n

🚀 지속적 통합 · 배포 (CI · CD)

GitHub Actions는 공개된 코드 저장소에 대해서는 기본적으로 무료이며 비공개 개인 저장소에 대해서도 계정당 기본 2,000분/월의 할당량이 제공됩니다³.

GitHub Pages를 이용하여 블로그를 호스팅하기로 한 만큼, 코드 저장소와 CI, 이슈 트래커 모두 GitHub을 이용하면 굳이 여러 사이트를 돌아다니지 않아도 필요한 모든 작업을 수행할 수 있습니다.

📜 최종 구성

대부분의 기초 코드(주로 설정 파일)는 기존에 구성해두었던 토이 프로젝트 중 가장 비슷한 성격(정적 웹 개발)의 프로젝트에서 가져왔습니다.

\n
언어: JavaScript / TypeScript (Node 20.x)
\n
형 검사가 지원되는 언어를 선호하기에 TypeScript를 선택했습니다. 형 검사는 간단한 테스트를 대체할 수 있으며 테스트보다 빠르게 잡아낼 수 있는 문법 오류도 많습니다.
\n
\n
웹 프레임워크: SvelteKit 1.x
\n
\n
CSS 디자인: Tailwind CSS + DaisyUI
\n
\n
단위 테스트: Vitest
\n
개발을 위해 Vite를 이용하고 있어서 Vitest를 이용했습니다. 정적 웹 사이트를 만드는 것이니 테스트의 중요도는 비교적 낮지만 기초적인 블로그 프레임워크를 만든다고 생각하고 빌드에 사용되는 여러 내부 요소에 대한 단위 테스트를 수행했습니다.
\n
\n
종단 간 테스트: Playwright
\n
완성된 웹 사이트에 대한 접근성, SEO 및 여러 평가를 수행하고자 했습니다. 어느정도는 수작업으로라도 하게 될 것이 눈에 선했기에 가능하면 자동화하고자 했습니다.
\n
\n
개발 환경 구성: Docker + VS Code Devcontainer
\n
최종 산출물이 정적 웹 사이트이기 때문에 Docker는 개발 컨테이너를 위해서만 사용했습니다.
\n
\n
지속적 통합 · 배포: GitHub Actions
\n
\n
작업 관리: GitHub Issues / Projects
\n

🏗️ 개발 과정

SvelteKit을 이용하여 정적 블로그를 만드는 좋은 글⁴을 찾을 수 있었습니다. 사실상 대부분의 기능은 이 글을 따라가는 것으로 충분할 정도였습니다.

별도 리팩토링 시간을 갖기보다는 수시로 코드를 검토하고 개선하며 진행했습니다. 새로운 라이브러리를 도입하거나, 구조를 뜯어고치기도 했습니다.

\n
date-fns
\n
시간과 관련된 지리(로케일) 설정, 서식 지정 등을 위해 사용했습니다.
\n
\n
zod
\n
타입, 인터페이스에 대한 테스트를 작성하는 건 귀찮고 재미없는 일입니다. Python의 Pydantic처럼 Zod를 통해 이를 대신하고자 했습니다.
\n

🎨 레이아웃

테스트 코드 작성 다음으로 전체 개발 기간 중 대부분을 차지했으며 가장 많이 바뀐 부분이 레이아웃입니다. 디자인 경험이 크게 부족하다는 것을 느꼈습니다.

디자인 경험이 거의 없기에 기초적인 레이아웃을 구상하는 데에도 꽤 애를 먹었습니다. 처음에는 대략적인 틀을 잡아보며 이것저것 시도하다 중간부터는 다른 블로그를 많이 참고했습니다. 주로 레이아웃을 참고했고, 시각 효과가 있는 요소는 내부 CSS를 파보고 구현 방법을 찾아보았습니다.

$\"레이아웃\"$

\n
상단 바 (Header)
\n
너무 많은 요소가 노출되지 않도록 했습니다. 헤더는 쉽게 눈에 띄는 요소인지라 하나여서 반응성을 가장 신경썼습니다. 처음에는 스티키(Sticky) 헤더로 만들었다가 앵커(#)를 따라 스크롤이 이동했을 때 요소를 가리는 문제가 있어 나중에 되돌렸습니다.
\n
요소를 가리는 문제는 scroll-padding-top CSS를 이용하여 해결할 수 있지만 치웠을 때 보기가 더 좋아서 헤더를 치우기로 결정했습니다.
\n
\n
측면 메뉴 바 (Sidebar)
\n
처음엔 프로필을 비롯한 다양한 기능을 사이드바에 넣어두었다가 블로그보다는 대시보드같은 느낌이 들어 제거했습니다.
\n
\n
하단 바 (Footer)
\n
당장은 넣을만한 것이 없어서 간단하게 만들어 두었습니다. 언젠가 사이트맵을 비롯해 여러 링크를 더 넣게 될 것 같습니다.
\n

그렇게 기초적인 레이아웃을 작업했지만 결국 단순한 게 제일이었다고 생각합니다. 초기 디자인을 대시보드를 참고하여 만들어서인지 블로그와 어울리지 않았습ㄴ다.

각종 시각 효과(트랜지션 등)는 CSS에 대해 한번 정리한 후에 제대로 작업하기로 했습니다. 어설프게 적용했다간 더 촌스러워질 것이 눈에 선했습니다.

🎨 테마

다양한 테마를 지원할 수 있도록 구현했습니다. 지금은 DaisyUI에서 제공하는 테마를 이용하고 있으나, 추후 직접 테마를 만들어보는 것도 괜찮을 것 같습니다.

\n
CSS 미디어 쿼리를 이용하여 사용자 선호 테마(Light / Dark)를 감지
\n
\n
브라우저 로컬 스토리지를 통해 이전 결정을 기억
\n
\n
실제로 테마 변경이 반영되게끔 HTML 요소(data-theme)를 변경하는 등, 호환성 레이어를 제공
\n

추후 DaisyUI가 아닌 다른 컴포넌트 라이브러리를 사용하더라도 테마 관련 코드만 조금 변경해주면 되도록 했습니다.

📸 프로필

프로필을 갱신할 때 마다 매번 웹 페이지를 다시 빌드하고 싶지는 않아서 Gravatar와 동기화하고자 했습니다. Gravatar API⁵를 이용했습니다.

$\"프로필\"$

GET HTTP 메소드를 이용하므로 쉽고 단순하며 공개된 정보에 접근하는 것이니 인증이 필요하지 않습니다. 지금 당장은 프로필 이미지만 동기화하고 있지만 API를 통해 JSON 객체로 표현된 프로필 정보를 가져오는 것 또한 가능하므로 추후에는 Gravatar 프로필 내용까지 동기화할 계획입니다.

📰 게시글

마크다운(.md) 파일을 직접 블로그 게시글로 사용하고자 했습니다. 각 마크다운 파일에 제목, 작성일자를 비롯한 다양한 메타데이터를 프론트 매터(Front Matter)로 저장해두고 페이지 렌더링에 이용하는 방법입니다.

처음엔 타 블로그⁴ 글을 따라 mdsvex를 이용해서 구현했지만 그 후에 rehype를 이용하여 다시 구현했습니다. 구현을 변경하게 된 이유는 다음과 같습니다.

\n
마크다운 문법에 대한 제약
\n
제약 사항이 많은 편은 아니고 치명적인 것도 아니지만 글을 쓸 때 가능하면 이런 제약 사항을 신경쓰고 싶지 않았습니다.
\n
\n
개발 도구의 혜택을 충분히 받을 수 없음
\n
Prettier, ESLint, TypeScript와 같은 도구의 힘을 빌리기가 어려웠습니다.
\n
\n
충분히 편리하지도, 유연하지도 않음
\n
레이아웃 컴포넌트를 변경하거나 rehype 플러그인을 추가함으로써 기능을 확장할 수 있지만 그렇다면 그냥 둘 다 직접 구현하는 편이 낫겠다는 생각이 들었습니다. mdsvex를 이용해 마크다운 문서 내에서 Svelte 컴포넌트를 사용할 수 있지만 반대로 어디서든 마크다운 요소를 이용할 수 있도록 컴포넌트를 구현하고자 했습니다.
\n

그렇게 구현된 코드입니다.

📰 목차

목차를 직접 관리하는 건 끔찍한 일이기에 게시글에 자동으로 목차를 생성하고자 했습니다. 다행히 이를 위해 사용 또는 참고할 수 있는 패키지가 존재합니다.

하지만 패키지를 이용하는 대신 직접 구현하기로 했습니다. 목차를 자유롭게 배치하고 싶었고 구현이 그리 복잡하지는 않을 것이라고 생각했기 때문입니다.

목차를 구현하기 위해 헤딩(h1 ~ h6)에 대한 들여쓰기를 어떻게 처리하는지 Notion을 참고했습니다.

$\"Notion$

헤딩 태그에 따라 들여쓰기 크기가 정해진 것이 아니라 중첩된 목록처럼 스타일이 적용됩니다. 태그마다 절댓값을 주면 구현이 쉽고 편하겠지만 범용성을 위해 조금 더 시간을 할애하기로 했습니다.

그렇게 주어진 헤딩의 1차원 리스트로부터 트리 자료구조를 생성하는 알고리즘과 컴포넌트를 구현(/src/lib/toc.ts, /src/components/content/Toc.svelte)했습니다. 알고리즘에 대한 공부가 게을렀던 탓인지 필히 어려운 문제가 아닌 것 같은데, 구현을 위해 생각보다 오랜 시간 머리를 싸매야 했습니다.

$\"목차\"$

내용이 많아졌을 때 가독성을 해치는 경우가 있어 추후 목차를 열고 닫을 수 있게끔 할 생각입니다.

🔍 검색

기본적인 게시글 검색 기능을 구현하고 싶어 MiniSearch 패키지를 이용했습니다. 구성과 사용 모두 간단합니다.

$\"검색$

당장은 제목과 태그만 인덱싱하고 있는데 언젠가는 내용에 대한 인덱싱 또한 추가하고 싶네요.

📬 RSS

어떤 블로그를 방문해도 RSS 피드를 쉽게 찾아볼 수 있죠. 그래서 RSS 피드를 제공하는 기능을 구현⁶했습니다.

🤖 SEO

구슬이 서 말이라도 꿰어야 보배라고, 글을 아무리 많이 쓰더라도 읽히지 않으면 소용이 없죠. 하지만 SEO에 관해서는 문외한인지라 당장은 Lighthouse CI를 추가하는 것으로 일단락했습니다.

먼저 Lighthouse CI GitHub 앱을 설치하고, 다음의 CI 작업(Job)을 추가합니다.

lighthouse:\n    name: Lighthouse\n    needs: deploy\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    steps:\n        - name: Checkout\n          uses: actions/checkout@v4\n\n        - name: Run Lighthouse CI\n          uses: treosh/lighthouse-ci-action@v10\n          env:\n              LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}\n          with:\n              runs: 3\n              configPath: ./.lighthouserc.json\n              budgetPath: ./budget.json\n              urls: |\n                  ${{ needs.deploy.outputs.page_url }}/\n                  ${{ needs.deploy.outputs.page_url }}/about-me\n                  ${{ needs.deploy.outputs.page_url }}/blog\n              temporaryPublicStorage: true\n

매 배포 후 Lighthouse 리포트가 생성됩니다.

$\"Lighthouse$

Details를 누르면 Google Cloud의 Temporary Public Storage에 저장된 LHCI 리포트를 볼 수 있습니다.

$\"Lighthouse$

🧪 자동화 테스트

FE 테스트에 대해서는 많은 지식이나 경험이 없는지라 크게 헤맸습니다. 전체 개발 소요 기간의 절반은 테스트를 작성하느라 보내지 않았을까 싶을 정도로요.

요구사항이 명확히 정의되지 않았고 프레임워크와 테스트 API에 대한 지식이 없는 상태에서 먼저 테스트를 작성하는 건 쉽지 않은 일이기 때문에 기능을 먼저 구현한 뒤 테스트를 작성하는 식으로 진행했습니다. 테스트를 써 버릇 하다보니 나중에는 기능을 구상하면서 먼저 요구사항을 머릿속으로 정리하고 어느정도 테스트를 미리 작성할 수 있게 되었습니다.

$\"Playwright$

종단 간 테스트를 위해 사용한 Playwright의 UI는 꽤 편리했습니다. VS Code 개발 컨테이너는 자동으로 X11 설정을 포워딩하므로 호스트 환경(내 경우 WSL)의 X Server를 통해 Playwright UI를 직접 이용할 수도 있습니다.

하지만 디스플레이가 여의치 않은 환경(e.g. GitHub Codespaces)은 noVNC 구성을 통해 웹 브라우저로 디스플레이를 이용할 수 있습니다.

✨ 완성, 그리고 정리

약 한달여간의 우여곡절 끝에 블로그를 완성했습니다. 소스 코드는 GitHub에 공개되어 있습니다.

예상보다 괜찮은 완성품이 나온 것 같아서 흡족하지만 부족한 점이 차고 넘칩니다. 아직 채워진 내용도 별로 없어서 허전합니다. 하지만 글과 내용을 하나 둘 채우고 필요한 기능들을 하나 둘 넣어가며 발전시켜 나가려고 합니다.

첫 글을 올리고 나면 당분간 미뤄두었던 토이 프로젝트에도 시간을 좀 할애할 예정이라, 다음 올라올 글이 무엇일지, 어떤 주제일지 모르겠습니다.

⏱️ 추후 계획

일단은 동작하는 결과물을 빠르게 내보이는 것을 목적으로 삼은 만큼 복잡하거나 어려운 기능, 당장 적용할 수 없을 것으로 보이는 기능은 나중으로 미뤘습니다.

\n
I18n
\n
라우팅부터 시작해서 영향 범위가 너무 커서 당초 예상보다 큰 시간과 노력이 필요한 기능인지라 일단은 보류하기로 했습니다. 충분한 지식이 있었다면 개발 초기부터 완전한 구성을 했겠지만.. 일단은 동작하는 기초적인 블로그를 만들고자 했습니다.
\n
\n
Gravatar 프로필 동기화
\n
Gravatar를 프로필 정보 원천으로 삼으려고 합니다. Gravatar는 여러 언어에 대한 프로필도 지원하므로 I18n과 같이 작업하게 될 것 같습니다.
\n
\n
댓글
\n
당장 필수적이진 않아서 보류했지만 높은 우선순위를 두고 있는지라 조만간 추가하려고 합니다. utterances를 이용하게 될 것으로 예상하지만 GitHub를 작업 관리를 위한 이슈 트래커로 이용하고 있어서 다른 방법을 찾을지도 모르겠네요.
\n
\n
CSS 컴포넌트 프레임워크 변경
\n
DaisyUI는 사용하기 쉬웠고 기본 제공되는 테마도 많지만 컴포넌트 수도 적고 전체적인 디자인이 지향점과 다소 어긋나는 부분이 있었습니다.
\n
\n
자원 관리
\n
첫 글을 작성하면서 이미지 자원을 관리하는 데 많은 애로사항을 느꼈습니다. 파일 경로가 달라 IDE의 마크다운 미리보기와 연동이 되지 않았고, 내용(/posts)과 이미지 자원(/static)이 서로 다른 경로에 존재하게 되어 불편했습니다. 당장은 rehype 플러그인을 작성해 임시 처리하고 있는데, 더 나은 방법을 모색해야 할 것 같네요.
\n
\n
Google Analytics
\n
필요보다는 흥미 본위에 의한 것으로, 그냥 넣어보고 싶은 기능입니다. 언젠가 트래픽이 많아진다면 사이트 개선을 위한 유의미한 정보를 제공해 줄지도.
\n
GA API를 이용하면 페이지 조회 관련 데이터 또한 얻을 수 있는 것으로 보이는데 이를 활용하면 조회수 또한 구현할 수 있지 않을까요.
\n
\n
Google AdSense
\n
언젠가는 광고도 넣었으면 합니다. 잠깐 확인해보니 어느 정도 컨텐츠가 쌓여야 심사⁷를 통과할 수 있다는 모양이라 어느 정도 글이 쌓이게 되면 광고를 추가하게 될 것 같습니다.
\n

\n
미디엄 수익 창출을 위한 파트너 프로그램 등록 불가능(?) ↩
\n
\n
Monthly included storage and core hours for personal accounts ↩
\n
\n
About billing for GitHub Actions ↩
\n
\n
Let's learn SvelteKit by building a static Markdown blog from scratch ↩ ↩²
\n
\n
Gravatar Developer Resources ↩
\n
\n
How to make an RSS feed in SvelteKit ↩
\n
\n
Eligibility requirements for AdSense ↩
\n

"}]